\hypertarget{access__ref_8h}{
\section{access\_\-ref.h File Reference}
\label{access__ref_8h}\index{access\_\-ref.h@{access\_\-ref.h}}
}


Access Reference Map module header.  


{\ttfamily \#include $<$stdbool.h$>$}\par
{\ttfamily \#include \char`\"{}crypto.h\char`\"{}}\par
{\ttfamily \#include \char`\"{}uthash.h\char`\"{}}\par
\subsection*{Data Structures}
\begin{DoxyCompactItemize}
\item 
struct \hyperlink{struct_map__t}{Map\_\-t}
\begin{DoxyCompactList}\small\item\em A hashable key-\/value pair for an access reference map. \item\end{DoxyCompactList}\end{DoxyCompactItemize}
\subsection*{Defines}
\begin{DoxyCompactItemize}
\item 
\hypertarget{access__ref_8h_adb7391c3aeef0d4e0299e4ace1d15408}{
\#define {\bfseries \_\-ACCESS\_\-REF\_\-H}}
\label{access__ref_8h_adb7391c3aeef0d4e0299e4ace1d15408}

\item 
\hypertarget{access__ref_8h_a32a183eeadf922d255d06a4e4f2aca66}{
\#define \hyperlink{access__ref_8h_a32a183eeadf922d255d06a4e4f2aca66}{KEY\_\-LEN}~7}
\label{access__ref_8h_a32a183eeadf922d255d06a4e4f2aca66}

\begin{DoxyCompactList}\small\item\em The fixed length of an access reference map key, generated by get\_\-unique\_\-reference(). \item\end{DoxyCompactList}\item 
\#define \hyperlink{access__ref_8h_a86369bddee02e95701be9bcca71cc1cf}{VAL\_\-LEN}~64
\begin{DoxyCompactList}\small\item\em The maximum length of an access reference map value. \item\end{DoxyCompactList}\end{DoxyCompactItemize}
\subsection*{Typedefs}
\begin{DoxyCompactItemize}
\item 
\hypertarget{access__ref_8h_ad3b65c8c1fd4f3c0d0fe8167c4f1d20e}{
typedef struct \hyperlink{struct_map__t}{Map\_\-t} {\bfseries map\_\-t}}
\label{access__ref_8h_ad3b65c8c1fd4f3c0d0fe8167c4f1d20e}

\end{DoxyCompactItemize}
\subsection*{Functions}
\begin{DoxyCompactItemize}
\item 
bool \hyperlink{access__ref_8h_a1e54a15dcdb26539c8ecdc307894008e}{esapi\_\-put\_\-reference} (const char $\ast$, const char $\ast$)
\begin{DoxyCompactList}\small\item\em Adds an entry to the map. \item\end{DoxyCompactList}\item 
char $\ast$ \hyperlink{access__ref_8h_ab073378238a896e3ffa11d929939e5bc}{esapi\_\-get\_\-indirect\_\-reference} (const char $\ast$)
\begin{DoxyCompactList}\small\item\em Returns the indirect object reference for the given direct object reference. \item\end{DoxyCompactList}\item 
char $\ast$ \hyperlink{access__ref_8h_a1f529c8289b4408f74f4a550d5b09e2b}{esapi\_\-get\_\-direct\_\-reference} (const char $\ast$)
\begin{DoxyCompactList}\small\item\em Returns the direct object reference (original value) for the given indirect object reference. \item\end{DoxyCompactList}\item 
bool \hyperlink{access__ref_8h_ac0782ecd23166146eecc5e70f46c48f1}{esapi\_\-remove\_\-direct\_\-reference} (const char $\ast$)
\begin{DoxyCompactList}\small\item\em Removes the direct object reference from the map. \item\end{DoxyCompactList}\item 
bool \hyperlink{access__ref_8h_a402b6330b4e3c5c92a74bb071fd19304}{esapi\_\-remove\_\-indirect\_\-reference} (const char $\ast$)
\begin{DoxyCompactList}\small\item\em Removes the indirect object reference from the map. \item\end{DoxyCompactList}\item 
char $\ast$ \hyperlink{access__ref_8h_a040da60c053ba72839be5a7824bd8d4b}{esapi\_\-get\_\-unique\_\-reference} ()
\begin{DoxyCompactList}\small\item\em Return a unique token string suitable for use as an indirect reference. \item\end{DoxyCompactList}\end{DoxyCompactItemize}
\subsection*{Variables}
\begin{DoxyCompactItemize}
\item 
\hypertarget{access__ref_8h_aa9002aaaac025497dd7f9546a46d7dd9}{
\hyperlink{struct_map__t}{map\_\-t} $\ast$ \hyperlink{access__ref_8h_aa9002aaaac025497dd7f9546a46d7dd9}{v\_\-map}}
\label{access__ref_8h_aa9002aaaac025497dd7f9546a46d7dd9}

\begin{DoxyCompactList}\small\item\em Value-\/to-\/key map. \item\end{DoxyCompactList}\item 
\hypertarget{access__ref_8h_a2f95b767fe7a7a166cc726b59799c0de}{
\hyperlink{struct_map__t}{map\_\-t} $\ast$ \hyperlink{access__ref_8h_a2f95b767fe7a7a166cc726b59799c0de}{k\_\-map}}
\label{access__ref_8h_a2f95b767fe7a7a166cc726b59799c0de}

\begin{DoxyCompactList}\small\item\em Key-\/to-\/value map. \item\end{DoxyCompactList}\end{DoxyCompactItemize}


\subsection{Detailed Description}
Access Reference Map module header. The Access Reference Map is used to map from a set of internal direct object references to a set of indirect references that are safe to disclose publicly. This can be used to help protect database keys, filenames, and other types of direct object references. As a rule, developers should not expose their direct object references as it enables attackers to attempt to manipulate them. 

Indirect references are handled as strings, to facilitate their use in GUI controls or service messages. 

Note that in addition to defeating all forms of parameter tampering attacks, there is a side benefit of the Access Reference Map. Using random strings as indirect object references, as opposed to simple integers makes it impossible for an attacker to guess valid identifiers. So if per-\/user Access Reference Maps are used, then request forgery attacks will also be prevented.


\begin{DoxyCode}
        char *value = "This is a direct object reference";
        esapi_put_reference(esapi_get_unique_reference(value), value);
\end{DoxyCode}


\begin{DoxySince}{Since}
January 30, 2011 
\end{DoxySince}


Definition in file \hyperlink{access__ref_8h_source}{access\_\-ref.h}.



\subsection{Define Documentation}
\hypertarget{access__ref_8h_a86369bddee02e95701be9bcca71cc1cf}{
\index{access\_\-ref.h@{access\_\-ref.h}!VAL\_\-LEN@{VAL\_\-LEN}}
\index{VAL\_\-LEN@{VAL\_\-LEN}!access_ref.h@{access\_\-ref.h}}
\subsubsection[{VAL\_\-LEN}]{\setlength{\rightskip}{0pt plus 5cm}\#define VAL\_\-LEN~64}}
\label{access__ref_8h_a86369bddee02e95701be9bcca71cc1cf}


The maximum length of an access reference map value. 

\begin{Desc}
\item[\hyperlink{todo__todo000009}{Todo}]Change to support dynamically sized values. \end{Desc}


Definition at line 47 of file access\_\-ref.h.



\subsection{Function Documentation}
\hypertarget{access__ref_8h_a1f529c8289b4408f74f4a550d5b09e2b}{
\index{access\_\-ref.h@{access\_\-ref.h}!esapi\_\-get\_\-direct\_\-reference@{esapi\_\-get\_\-direct\_\-reference}}
\index{esapi\_\-get\_\-direct\_\-reference@{esapi\_\-get\_\-direct\_\-reference}!access_ref.h@{access\_\-ref.h}}
\subsubsection[{esapi\_\-get\_\-direct\_\-reference}]{\setlength{\rightskip}{0pt plus 5cm}char$\ast$ esapi\_\-get\_\-direct\_\-reference (
\begin{DoxyParamCaption}
\item[{const char $\ast$}]{}
\end{DoxyParamCaption}
)}}
\label{access__ref_8h_a1f529c8289b4408f74f4a550d5b09e2b}


Returns the direct object reference (original value) for the given indirect object reference. 


\begin{DoxyParams}{Parameters}
{\em A} & character array containing an indirect object reference \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
A character array containing a direct object reference 
\end{DoxyReturn}


Definition at line 64 of file access\_\-ref.c.

\hypertarget{access__ref_8h_ab073378238a896e3ffa11d929939e5bc}{
\index{access\_\-ref.h@{access\_\-ref.h}!esapi\_\-get\_\-indirect\_\-reference@{esapi\_\-get\_\-indirect\_\-reference}}
\index{esapi\_\-get\_\-indirect\_\-reference@{esapi\_\-get\_\-indirect\_\-reference}!access_ref.h@{access\_\-ref.h}}
\subsubsection[{esapi\_\-get\_\-indirect\_\-reference}]{\setlength{\rightskip}{0pt plus 5cm}char$\ast$ esapi\_\-get\_\-indirect\_\-reference (
\begin{DoxyParamCaption}
\item[{const char $\ast$}]{}
\end{DoxyParamCaption}
)}}
\label{access__ref_8h_ab073378238a896e3ffa11d929939e5bc}


Returns the indirect object reference for the given direct object reference. 


\begin{DoxyParams}{Parameters}
{\em A} & character array containing a direct object reference \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
A character array containing an indirect object reference 
\end{DoxyReturn}


Definition at line 50 of file access\_\-ref.c.

\hypertarget{access__ref_8h_a040da60c053ba72839be5a7824bd8d4b}{
\index{access\_\-ref.h@{access\_\-ref.h}!esapi\_\-get\_\-unique\_\-reference@{esapi\_\-get\_\-unique\_\-reference}}
\index{esapi\_\-get\_\-unique\_\-reference@{esapi\_\-get\_\-unique\_\-reference}!access_ref.h@{access\_\-ref.h}}
\subsubsection[{esapi\_\-get\_\-unique\_\-reference}]{\setlength{\rightskip}{0pt plus 5cm}char$\ast$ esapi\_\-get\_\-unique\_\-reference (
\begin{DoxyParamCaption}
{}
\end{DoxyParamCaption}
)}}
\label{access__ref_8h_a040da60c053ba72839be5a7824bd8d4b}


Return a unique token string suitable for use as an indirect reference. 

\begin{DoxyReturn}{Returns}
A character array containing an indirect object reference 
\end{DoxyReturn}


Definition at line 131 of file access\_\-ref.c.



References esapi\_\-fill\_\-random\_\-token(), and KEY\_\-LEN.

\hypertarget{access__ref_8h_a1e54a15dcdb26539c8ecdc307894008e}{
\index{access\_\-ref.h@{access\_\-ref.h}!esapi\_\-put\_\-reference@{esapi\_\-put\_\-reference}}
\index{esapi\_\-put\_\-reference@{esapi\_\-put\_\-reference}!access_ref.h@{access\_\-ref.h}}
\subsubsection[{esapi\_\-put\_\-reference}]{\setlength{\rightskip}{0pt plus 5cm}bool esapi\_\-put\_\-reference (
\begin{DoxyParamCaption}
\item[{const char $\ast$}]{, }
\item[{const char $\ast$}]{}
\end{DoxyParamCaption}
)}}
\label{access__ref_8h_a1e54a15dcdb26539c8ecdc307894008e}


Adds an entry to the map. 

The indirect reference should be obtained by calling \hyperlink{access__ref_8c_a040da60c053ba72839be5a7824bd8d4b}{esapi\_\-get\_\-unique\_\-reference()}. 
\begin{DoxyParams}{Parameters}
{\em A} & character array containing an indirect object reference \\
\hline
{\em A} & character array containing a direct object reference \\
\hline
\end{DoxyParams}
\begin{DoxySeeAlso}{See also}
\hyperlink{access__ref_8c_a040da60c053ba72839be5a7824bd8d4b}{esapi\_\-get\_\-unique\_\-reference()} 
\end{DoxySeeAlso}


Definition at line 110 of file access\_\-ref.c.

\hypertarget{access__ref_8h_ac0782ecd23166146eecc5e70f46c48f1}{
\index{access\_\-ref.h@{access\_\-ref.h}!esapi\_\-remove\_\-direct\_\-reference@{esapi\_\-remove\_\-direct\_\-reference}}
\index{esapi\_\-remove\_\-direct\_\-reference@{esapi\_\-remove\_\-direct\_\-reference}!access_ref.h@{access\_\-ref.h}}
\subsubsection[{esapi\_\-remove\_\-direct\_\-reference}]{\setlength{\rightskip}{0pt plus 5cm}bool esapi\_\-remove\_\-direct\_\-reference (
\begin{DoxyParamCaption}
\item[{const char $\ast$}]{}
\end{DoxyParamCaption}
)}}
\label{access__ref_8h_ac0782ecd23166146eecc5e70f46c48f1}


Removes the direct object reference from the map. 


\begin{DoxyParams}{Parameters}
{\em A} & character array containing a direct object reference \\
\hline
\end{DoxyParams}


Definition at line 95 of file access\_\-ref.c.

\hypertarget{access__ref_8h_a402b6330b4e3c5c92a74bb071fd19304}{
\index{access\_\-ref.h@{access\_\-ref.h}!esapi\_\-remove\_\-indirect\_\-reference@{esapi\_\-remove\_\-indirect\_\-reference}}
\index{esapi\_\-remove\_\-indirect\_\-reference@{esapi\_\-remove\_\-indirect\_\-reference}!access_ref.h@{access\_\-ref.h}}
\subsubsection[{esapi\_\-remove\_\-indirect\_\-reference}]{\setlength{\rightskip}{0pt plus 5cm}bool esapi\_\-remove\_\-indirect\_\-reference (
\begin{DoxyParamCaption}
\item[{const char $\ast$}]{}
\end{DoxyParamCaption}
)}}
\label{access__ref_8h_a402b6330b4e3c5c92a74bb071fd19304}


Removes the indirect object reference from the map. 


\begin{DoxyParams}{Parameters}
{\em A} & character array containing an indirect object reference \\
\hline
\end{DoxyParams}


Definition at line 78 of file access\_\-ref.c.

